# 🐛 MCP Server Fails in Claude Desktop on macOS (Permissions + Read-Only FS Issues)
## Summary
When attempting to run the `meraki-magic-mcp` server inside Claude Desktop on macOS, the MCP server repeatedly failed to initialize due to:
1. Virtual environment permission errors
2. Broken virtual environment after folder move
3. Read-only filesystem errors caused by SDK file caching
This issue documents the root causes and final resolution so future developers avoid the same pitfalls.
---
# Environment
* macOS
* Claude Desktop (MCP stdio transport)
* Python virtual environment (`.venv`)
* `fastmcp`
* Meraki Python SDK
* Local MCP server: `meraki-mcp-dynamic.py`
---
# Timeline of Errors & Root Causes
---
## 1️⃣ Initial Failure — Python Permission Error
### Error
```
Fatal Python error: init_import_site: Failed to import the site module
PermissionError: [Errno 1] Operation not permitted:
'/Users/amitsi4/Documents/MCP/meraki-magic-mcp/.venv/pyvenv.cfg'
```
### Root Cause
Claude Desktop did not have permission to access the `Documents` directory.
macOS privacy sandbox prevented Python from reading the virtual environment config.
### Resolution
* Moved project out of `Documents`
* Recreated virtual environment
* Ensured correct ownership and permissions
---
## 2️⃣ ENOENT After Moving Folder
### Error
```
spawn .../.venv/bin/fastmcp ENOENT
```
### Root Cause
Virtual environments contain absolute paths internally.
After moving the project folder, the `.venv` symlinks were invalid.
### Resolution
Recreated virtual environment:
```bash
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
---
## 3️⃣ Final Failure — Read-Only Filesystem
### Error
```
Failed to run server: [Errno 30] Read-only file system: '.meraki_cache'
```
### Root Cause
Claude Desktop runs MCP servers in a restricted sandbox.
The Meraki SDK (and custom response caching) attempted to create:
```
.meraki_cache
```
This is a relative path (`./.meraki_cache`), and the working directory is read-only in Claude’s MCP environment.
Even with `ENABLE_CACHING=false`, file-based response caching was still enabled:
```env
ENABLE_FILE_CACHING=true
RESPONSE_CACHE_DIR=.meraki_cache
```
The server attempted to create that directory during initialization → crash.
---
# ✅ Final Resolution
Disabled file-based caching in `.env`:
```env
ENABLE_CACHING=false
ENABLE_FILE_CACHING=false
```
Server now starts and initializes successfully in Claude Desktop.
---
# 🧠 Important Lessons for MCP Server Development
### Claude Desktop MCP Sandbox Behavior
* ✅ Network access allowed
* ✅ stdin/stdout allowed
* ⚠️ Working directory should be treated as read-only
* ⚠️ Relative filesystem writes will fail
### Best Practices Going Forward
1. Avoid relative write paths like:
```
.cache
.logs
.anything
```
2. If file writes are required, use:
* `/tmp`
* `~/Library/Caches`
* `tempfile.gettempdir()` in Python
Example safe pattern:
```python
import tempfile
import os
cache_dir = os.path.join(tempfile.gettempdir(), "meraki_cache")
```
3. Do not assume local filesystem write access in MCP environments.
---
# 📌 Recommendation
If caching is required in the future, update:
```env
RESPONSE_CACHE_DIR=/tmp/meraki_cache
ENABLE_FILE_CACHING=true
```
Or modify server code to dynamically resolve a writable temp directory.
---
# Status
✅ Resolved
✅ MCP server now connects and runs successfully in Claude Desktop
⚠️ Future contributors should avoid relative filesystem writes
---
